<!DOCTYPE html>
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <title>Install iRedAdmin on FreeBSD</title>
        <link rel="stylesheet" type="text/css" href="./css/markdown.css" />
    </head>
    <body>

    <div id="navigation">
    <a href="https://www.iredmail.org" target="_blank">
        <img alt="iRedMail web site"
             src="./images/logo-iredmail.png"
             style="vertical-align: middle; height: 30px;"
             />&nbsp;
        <span>iRedMail</span>
    </a>
    &nbsp;&nbsp;//&nbsp;&nbsp;<a href="./index.html">Document Index</a></div><h1 id="install-iredadmin-on-freebsd">Install iRedAdmin on FreeBSD</h1>
<div class="admonition attention">
<p class="admonition-title">Attention</p>
<p>Check out the lightweight on-premises email archiving software developed by iRedMail team: <a href="https://spiderd.io/">Spider Email Archiver</a>.</p>
</div>
<div class="toc">
<ul>
<li><a href="#install-iredadmin-on-freebsd">Install iRedAdmin on FreeBSD</a><ul>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#download-iredadmin-and-configure-apache-web-server">Download iRedAdmin and configure Apache web server</a></li>
<li><a href="#create-required-mysql-database-and-grant-privileges">Create required MySQL database and grant privileges</a></li>
<li><a href="#configure-iredadmin">Configure iRedAdmin</a></li>
<li><a href="#access-iredadmin">Access iRedAdmin</a></li>
<li><a href="#troubleshooting-debug">Troubleshooting &amp; Debug</a></li>
</ul>
</li>
</ul>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>This tutorial is out of date and deprecated. Since iRedMail-0.9.8, Apache
was removed and Nginx is the only one web server.</p>
</div>
<blockquote>
<p>This tutorial is used to install iRedAdmin from scratch, running under Apache
web server.</p>
<p>If you already have iRedAdmin open source edition or old iRedAdmin-Pro release
installed, you can simply migrate it to the latest iRedAdmin by follow our short
tutorial: <a href="./migrate.or.upgrade.iredadmin.html">Migrate or upgrade iRedAdmin</a>.</p>
</blockquote>
<h2 id="requirements">Requirements</h2>
<p>iRedMail will install all required packages for you, you don't need to
install them manually, below info just for your reference.</p>
<ul>
<li>
<p>The latest iRedMail release. <a href="https://www.iredmail.org/download.html">Download the latest iRedMail</a>.
  NOTE: You must have iRedMail installed on server first.</p>
</li>
<li>
<p><code>Apache</code> 2.2+. Web server.</p>
<ul>
<li><code>mod_wsgi</code> 2.1+. Apache module used to host Python application which supports the Python WSGI interface.</li>
</ul>
</li>
<li>
<p><code>Python</code> 2.4+, core programming language. Warning: Python 3.x is not supported yet.</p>
<ul>
<li><code>web.py</code>, 0.32+. A python-powered web framework.</li>
<li><code>MySQLdb</code>: A thread-compatible interface to the popular MySQL database server that provides the Python database API. Required if you store mail accounts in OpenLDAP, MySQL or MariaDB.</li>
<li><code>Python-LDAP</code> 2.3.7+: An object-oriented API to access LDAP directory servers from Python programs. Required if you store mail accounts in OpenLDAP.</li>
<li><code>Python-psycopg2</code>: interface to the PostgreSQL database server from Python programs. Required if you store mail accounts in PostgreSQL.</li>
</ul>
</li>
</ul>
<h2 id="download-iredadmin-and-configure-apache-web-server">Download iRedAdmin and configure Apache web server</h2>
<ul>
<li>
<p>Download iRedAdmin open source edition <a href="https://dl.iredmail.org/yum/misc/">here</a>.
  If you're trying to install iRedAdmin-Pro, please <a href="https://www.iredmail.org/contact.html">contact us</a>
  to get download link of iRedAdmin-Pro.</p>
</li>
<li>
<p>Copy iRedAdmin to <code>/usr/local/www/</code>, set correct file permissions, and create symbol link.</p>
</li>
</ul>
<pre><code># tar xjf iRedAdmin-x.y.z.tar.bz2 -C /usr/local/www/
# cd /usr/local/www/
# chown -R iredadmin:iredadmin iRedAdmin-x.y.z
# chmod -R 0555 iRedAdmin-x.y.z
# ln -s iRedAdmin-x.y.z iredadmin
</code></pre>
<ul>
<li>Add apache configure file: <code>/usr/local/etc/apache22/Includes/iredadmin.conf</code>:</li>
</ul>
<pre><code>WSGISocketPrefix /var/run/wsgi
WSGIDaemonProcess iredadmin user=iredadmin threads=15
WSGIProcessGroup iredadmin

AddType text/html .py

&lt;Directory /usr/local/www/iredadmin/&gt;
    Order deny,allow
    Allow from all
&lt;/Directory&gt;
</code></pre>
<ul>
<li>Edit <code>/usr/local/etc/apache22/extra/httpd-ssl.conf</code>, make iredadmin accessible via HTTPS.
  Add below lines before <code>&lt;/VirtualHost&gt;</code>:</li>
</ul>
<pre><code>WSGIScriptAlias /iredadmin /usr/local/www/iredadmin/iredadmin.py/
Alias /iredadmin/static /usr/local/www/iredadmin/static/
</code></pre>
<ul>
<li>Restart apache to enable mod_wsgi:</li>
</ul>
<pre><code># /usr/local/etc/rc.d/apache22 restart
</code></pre>
<h2 id="create-required-mysql-database-and-grant-privileges">Create required MySQL database and grant privileges</h2>
<ul>
<li>Create MySQL database: <code>iredadmin</code>.</li>
</ul>
<pre><code># mysql -uroot -p
mysql&gt; CREATE DATABASE iredadmin DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;
mysql&gt; USE iredadmin;
mysql&gt; SOURCE /usr/local/www/iredadmin/docs/samples/iredadmin.sql;
</code></pre>
<ul>
<li>Grant privileges to iredadmin user and set password for it. WARNING: Here we
  use 'secret_passwd' as password of iredadmin user, please replace it with
  your own password.</li>
</ul>
<pre><code># mysql -uroot -p
mysql&gt; GRANT SELECT,INSERT,UPDATE,DELETE ON iredadmin.* TO iredadmin@localhost IDENTIFIED BY 'secret_passwd';
mysql&gt; FLUSH PRIVILEGES;
</code></pre>
<h2 id="configure-iredadmin">Configure iRedAdmin</h2>
<ul>
<li>
<p>Copy sample config file, and make it not world-writeable.</p>
<ul>
<li>settings.py.ldap.sample: sample config file for OpenLDAP backend</li>
<li>settings.py.mysql.sample: sample config file for MySQL/MariaDB backend</li>
<li>settings.py.pgsql.sample: sample config file for PostgreSQL backend</li>
</ul>
</li>
</ul>
<pre><code># cd /usr/local/www/iredadmin/
# cp settings.py.[backend].sample settings.py
# chown iredadmin:iredadmin settings.py
# chmod 0400 settings.py
</code></pre>
<ul>
<li>
<p>Update settings.py with correct values. Please read <code>settings.py</code> for more
  information, it's self-documented.</p>
</li>
<li>
<p>Restart apache web server.</p>
</li>
</ul>
<pre><code># /usr/local/etc/rc.d/apache22 restart
</code></pre>
<h2 id="access-iredadmin">Access iRedAdmin</h2>
<p>Open your web browser to access iRedAdmin: <code>https://your_server_ip_address/iredadmin/</code></p>
<p>Make sure you use <code>HTTPS://</code> instead of <code>HTTP://</code>.</p>
<h2 id="troubleshooting-debug">Troubleshooting &amp; Debug</h2>
<p>If iRedAdmin doesn't work as expected, you can simplily set <code>DEBUG = True</code> in
<code>settings.py</code>, restart apache web server, use your favourite web browser to
access it again, create a new <a href="https://forum.iredmail.org/">forum</a> topic and
paste error message in your forum topic.</p><div class="footer">
    <p style="text-align: center; color: grey;">All documents are available in <a href="https://github.com/iredmail/docs/">GitHub repository</a>, and published under <a href="http://creativecommons.org/licenses/by-nd/3.0/us/" target="_blank">Creative Commons</a> license. You can <a href="https://github.com/iredmail/docs/archive/master.zip">download the latest version</a> for offline reading. If you found something wrong, please do <a href="https://www.iredmail.org/contact.html">contact us</a> to fix it.</p>
</div></body></html>